Night Owl 6/Night Owl's Shareware - PDSI-006 - Night Owl Corp (1990).iso/039a/uw201.zip/UW_HELP4.HLP

Text File | 1991-10-07 | 24KB | 571 lines

`co(4,7);─────────────────────── /// Rectangle Functions ────────────────────────────`co();

┌──────────────────────────────────────────────────────────────────────────┐
│          `keyword(set_rect,/// set_rect);                  `keyword(rect_equal,/// rect_equal);        `keyword(rect_overlap,/// rect_overlap);        │
│          `keyword(offset_rect,/// offset_rect);               `keyword(cr_inrect,/// cr_inrect);                             │
└──────────────────────────────────────────────────────────────────────────┘

        The UltraWin library uses the structure RECT to handle information
    dealing with rectangular sections of the screen, as in the WINDOW
    structure.    Included are functions to define the rectangle, check to
    see if one rectangle overlaps another, and several other routines
    that you may wish to utilize in your program.

`co(10,1);/// set_rect`co();   `keyword(source,[UW_WIN.C]~set_rect);
    Takes the variable of type RECT passed by pointer, and sets the upper
    left corner and lower right corner to the coordinates passed as
    integers.

Prototype:
    void set_rect(RECT *rectp, int x1, int y1, int x2, int y2);

Parameters:
`co(11,1);    RECT *rectp;`co();
        A pointer to the rectangle variable.
`co(11,1);    int x1, y1, x2, y2`co();
        The coordinate pair for the upper left corner (x1,y1) and the
        lower right corner (x2,y2) of the rectangle.

Usage:
    RECT r;
    ...
    set_rect( &r, 10, 10, 20, 20 );

`co(10,1);/// rect_equal`co();   `keyword(source,[UW_WIN.C]~rect_equal);
    Checks to see if the two rectangles are the same.

Prototype:
    int rect_equal(RECT r1, RECT r2);

Parameters:
`co(11,1);    RECT r1, r2;`co();
        The two rectangles to compare.

Usage:
    RECT r1, r2;
    ...
    if (rect_equal( r1, r2 )) {}

`co(10,1);/// rect_overlap`co();   `keyword(source,[UW_WIN.C]~rect_overlap);
    Reports on the relationship between two windows.  This function
    will return the status as one of the following (defined in uw.h):
        1) FIRST_ENCLOSED
                 The first rectangle is enclosed within the second.
        2) SECOND_ENCLOSED
                 The second rectangle is enclosed within the first.
        3) OVERLAP
                 The rectangles overlap
        4) NO_OVERLAP
                 The rectangles do not overlap.

Prototype:
    int rect_overlap(RECT *r1, RECT *r2);

Parameters:
`co(11,1);    RECT r1, r2;`co();
        The two rectangles whose relationship to find.

Usage:
    RECT r1, r2;
    int status;
    ...
    status = rect_overlap( r1, r2 );

`co(10,1);/// offset_rect`co();   `keyword(source,[UW_WIN.C]~offset_rect);
    Moves the rectangles coordinates by a fixed amount in both the
    x (column) and y (row) direction.  The fixed amount can either
    be positive or negative.

Prototype:
    void offset_rect(RECT *rectp, int col, int row);

Parameters:
`co(11,1);    RECT *rectp;`co();
        A pointer to the rectangle variable.
`co(11,1);    int col, row`co();
        The offsets to add to the rectangle's coordinates.

Usage:
    RECT r;
    ...
    offset_rect( &r, 5, -4 );

`co(10,1);/// cr_inrect`co();   `keyword(source,[UW_WIN.C]~cr_inrect);
    Check to see if a particular location is inside (or on the border
    of) the rectangle passed.

Prototype:
    int cr_inrect(int col, int row, RECT rect);

Parameters:
`co(11,1);    int col, row`co();
        The coordinate to see if it lies in the rectangle.
`co(11,1);    RECT r;`co();
        The rectangle to check.

Usage:
    RECT r;
    ...
    if (cr_inrect( 5, 5, r )) {}

`co(4,7);──────────────────────────── /// Data Entry ────────────────────────────────`co();

┌──────────────────────────────────────────────────────────────────────────┐
│           `keyword(wn_gets,/// wn_gets);                            `keyword(Masks/Templates,/// Masks/Templates);             │
│           `keyword(Validation Chars,/// Validation Chars);                   `keyword(Strip Mask Option,/// Strip Mask Option);           │
└──────────────────────────────────────────────────────────────────────────┘

    One of the most flexible of all functions in the UltraWin library
    is wn_gets.  With this one function you can have the user enter
    dates, times, prices, strings, and any other type will full
    control over every character entered!  UltraWin V2.00 adds an even
    more powerful lower level function now called by wn_gets to enhance
    the capabilities even further.  Full compatibility is maintained.
  The new function called wn_gets_ll (which wn_gets calls) has added
  the capability to uppercase the first char of each word, strip the
  mask completely, only strip the end, or not strip at all.  More
  importantly, it can allow the user to input a string longer than the
  display width of the field and will scroll within this region
  automatically! It can also display arrows to show the user that the
  string has data to the left or right of the current display field.
  If this isn't enough for you, we've added the ability to call your own
  validation function for every key pressed in wn_gets_ll!  This allows
  you to validate the user's input "as it happens", and allows you to
  customize the validation routine for any data entry task.
  see `keyword(set_validation_func,/// set_validation_func);

`co(10,1);/// wn_gets`co();   `keyword(source,[UW_ENTRY.C]~wn_gets);
    Get input from the user according to the restrictions of the mask
    and template strings in the window passed by pointer.  This
    function will pass back the input either with the mask characters
    included in the string, or stripped out.    A -1 is returned if the
    mouse is clicked off of the string, and one of the values KEY_UP,
    KEY_DN, KEY_PGUP, KEY_PGDN, KEY_ESC, KEY_ENTER or KEY_TAB (all
    defined in uw.h) are returned if pressed.  Read about the mask and
    template strings for more information.

Prototype:
    int wn_gets( char *str, char *mask, char *template, int m_att,
                            int strip_mode, WINDOW *wnp );

Parameters:
`co(11,1);    char *str`co();
        The string to be returned by the function.
`co(11,1);    char *mask`co();
        The mask string.
`co(11,1);    char *template`co();
        The template string.
`co(11,1);    int m_att`co();
        The attribute (colors) to use when displaying the string.
`co(11,1);    int strip_mode`co();
        Set to 1 (STRIP_ON) to strip mask characters out of result,
        or set to 0 (STRIP_OFF) for full mask and result.
`co(11,1);    WINDOW *wnp;`co();
        A pointer to the window in which entry is to take place.

Usage:
    WINDOW *wnp;
    int result;
    char s[80];
    ...
    result = wn_gets( s, "(___)-___-____", "###  ### ####",
                                        wnp->att, STRIP_ON, wnp);

`co(10,1);/// wn_gets_ll`co();   `keyword(source,[UW_ENTRY.C]~wn_gets_ll);
    This function has the same capabilities as wn_gets() and more. wn_gets_ll
    has the capability to uppercase the first char of each word, strip the
  mask completely, only strip the end, or not strip at all.  More
  importantly, it can allow the user to input a string longer than the
  display width of the field and will scroll within this region
  automatically! It can also display arrows to show the user that the
  string has data to the left or right of the current display field.
  If this isn't enough or you, we've added the ability to call your own
  validation function for every key pressed in wn_gets_ll!  This allows
  you to validate the user's input "as it happens", and allows you to
  customize the validation routine for any data entry task.
  see `keyword(set_validation_func,/// set_validation_func);

Prototype:
    int wn_gets_ll( char *str, char *mask, char *template, int m_att,
                            int flags, int disp_width, WINDOW *wnp );

Parameters:
`co(11,1);    char *str`co();
        The string to be returned by the function.
`co(11,1);    char *mask`co();
        The mask string.
`co(11,1);    char *template`co();
        The template string.
`co(11,1);    int m_att`co();
        The attribute (colors) to use when displaying the string.
`co(11,1);    int flags`co();
   G_STRIP        strips the entire mask from the string.
                * 12/04/91 = 120491, (432)-555-3421 = 4325553421
   G_STRIP_END    strips the end of the string only.
                * John Doe____ = John Doe
   G_UP_FST_CHAR  convert the first letter of each word to uppercase
                * this is a test = This Is A Test
   G_ARROW        displays left and right arrows if display width is less
                  than field width. NOTE: This requires an additional
                  screen/window space before and after the field.
   G_VALIDATE     call the validation function set by `keyword(set_validation_func,/// set_validation_func);
`co(11,1);    int disp_width`co();
        The number of characters to display.  If less than the length of
        the input field, the display field will scroll.

`co(11,1);    WINDOW *wnp;`co();
        A pointer to the window in which entry is to take place.

Usage:
    WINDOW *wnp;
    int result;
    char s[80];
    ...
/*---- strip mask, convert first character of each word to uppercase, -----*/
/*------- and only display 6 characters, using arrows to show more --------*/
    result = wn_gets_ll( s, "______________", "AAAAAAAAAAAAA", wnp->att,
        G_STRIP | G_UP_FIRST_CHAR | G_ARROW, 6, wnp);

`co(10,1);/// Masks/Templates`co();

    The wn_gets function requires the programmer to specify two
    important strings to perform its magic.  These are the mask and
    template strings.

    The mask string gives the programmer the flexibility of displaying
    textual information inside the area to be typed by the user.    When
    the user types, the cursor simply skips over the mask characters.

    The template string is essentially a string containing validation
    characters.  Before a character is entered into the string, the
    wn_gets function compares the typed character with the template
    to see if the character is valid.  In addition, the template can
    be used to force an uppercase or lowercase character without having
    the user touch the CapsLock or Shift keys.

    When combined, the mask and template strings give the programmer
    great flexibility.    The following are just a few examples with
    explanations of what they accomplish:

    mask = "________"           Enter an 8 character string, where all
    tplt = "AAAAAAAA"           characters must be alphanumeric.

    mask = "________"           Enter an 8 character string, where
    tplt = "********"           anything typed is valid.

    mask = "________"           Enter an 8 character string, where the
    tplt = "Uaaaaaaa"           first character is converted to
                                                            uppercase, and the rest must be alpha.

    mask = "________"           Enter an 8 character string, where all 8
    tplt = "uuuuuuuu"           characters must by typed in uppercase.

    mask = "(___) ___-____"     Enter a 14 character string, where only
    tplt = " ###  ### ####"     numbers can be typed at the _ positions.


`co(10,1);/// Validation Chars`co();

    Validation characters are simply characters that are valid to put
    in your templates.    The following is a list of the validation
    characters along with their effect.

    Validation Char          Effect
    ---------------          -----------------------------------------------
             '#'             Allow only a digit to be entered.
             'X'             Allow only a hexidecimal digit to be entered.
             'u'             Allow only upper case letters to be entered.
             'l'             Allow only lower case letters to be entered.
             'U'             Convert to upper case, even if typed as lower.
             'L'             Convert to lower case, even if typed as upper.
             'A'             Allow only alphanumeric characters and <space>.
             'a'             Allow only alpha characters and <space>.
             '*'             Allow any characters.

`co(10,1);/// Strip Mask Option`co();

    This parameter to the wn_gets function gives the programmer the
    option to have wn_gets either format the string with the mask
    characters intact, or strip out the mask characters.    This can
    best be demonstrated as follows:

    mask = "(___) ___-____"
    tplt = " ###  ### ####"

    When wn_gets is called with these parameters, and a phone number is
    entered, the display looks like this:

                                                        [phone]

    Very simply, if the strip mask option is not used, then this string
    is what is returned by the function (mask intact).    However, if the
    strip mask option is used, then the returned string would be:

                                                             1234567890

    with no mask characters left, only what the user typed!  By utilizing
    this parameter in appropriate places you can save yourself a considerable
    amount of work.

`co(10,1);/// set_validation_func`co();   `keyword(set_validation_func,[UW_ENTRY.C]~set_validation_func);
    This allows you to set your own data entry validation function that
    is called every time a character is typed in `keyword(wn_gets_ll,/// wn_gets_ll);
  Note that this is not necessarily called for every keystroke.  If the
  user pressed the arrow keys, backspace, etc. the function will not be
  called.  It is called only when entering data.  When the function is
  called it is passed a series of parameters that allow complete flexibility.
  The validation routine should return a 1 if all's well, else it should
  return a 0.  If 0 is returned, the entry routine will overwrite the
  invalid character with the mask character for the current position.
  See the demo program `keyword(str_demo,[STR_DEMO.C]main); for more details.

Prototype:
void set_validation_func( int (*func_ptr)() )

Parameters:
  func_ptr - a function pointer which is called fo each character entry

Usage:
    set_validation_func( date_vld );
...
int date_vld(char *w, char *t, char *m, int pos, int max_pos, WINDOW *wnp )
{
    /* w       - pointer to current work string */
    /* m       - pointer to the mask            */
    /* m       - pointer to the template        */
    /* pos     - current position in string     */
    /* max_pos - maximum position in string     */
    /* WINDOW  - pointer to entry window (can be used to output err msg,etc) */
}

`co(4,7);───────────────────────────── /// Menuing ──────────────────────────────────`co();

┌──────────────────────────────────────────────────────────────────────────┐
│          `keyword(menu_create,/// menu_create);             `keyword(menu_destroy,/// menu_destroy);          `keyword(menu_set,/// menu_set);          │
│          `keyword(menu_restore,/// menu_restore);            `keyword(item_add,/// item_add);              `keyword(do_menu,/// do_menu);           │
│          `keyword(menu_system,/// menu_system);                                                     │
└──────────────────────────────────────────────────────────────────────────┘

    Another feature of the UltraWin library is menuing.  UltraWin allows
    both vertical and horizontal menus to be easily created and displayed
    for interaction with the user.    The menu's entries can be selected with
    just one keystroke (or a simple click of the mouse).  The letter to
    check when selecting an entry can be any character of the entry, and
    can even be highlighted in a different color.  In addition, the menus
    can be defined as a popup menu, restoring the area under the menu when
    finished, or it can be used with the window manager, forcing redraw
    of the area(s) of the window(s) below the menu when finished.

`co(10,1);/// menu_create`co();   `keyword(source,[UW_MENU.C]~menu_create);
    Initializes the menu to the specified coordinates on the screen,
    the menu attributes (colors), the border style and menu type
    passed.  A call to this function must be made to define the menu
    before the menu is placed on the screen with menu_set.    For
    the type parameter, use WN_POPUP if you wish the menu to be a
    popup menu (restoring the screen below), or WN_NORMAL if you are
    using UltraWin's powerful window manager.

Prototype:
    void menu_create(int x_min, int y_min, int x_max, int y_max,
                                 int direction, int back_att, int bdr_att, int csr_att,
                                 int first_att, int bdr, int type, MENU *mnp);

Parameters:
`co(11,1);    int x_min, y_min`co();
        The upper left corner of the menu to create.
`co(11,1);    int x_max, y_max`co();
        The lower right corner of the menu to create.
`co(11,1);    int direction`co();
        The menu direction, use M_VERTICAL for a vertical menu and
        M_HORIZONTAL for a horizontal menu.
`co(11,1);    int back_att`co();
        The attribute to use for the menu.    This defines the color of
        the menu and the characters in the menu, and can be a value from
        0-255.    For example, use (RED << 4) | WHITE for white menu entry
        characters on a red background.
`co(11,1);    int bdr_att`co();
        The border attribute (not used if the bdr parameter is NO_BDR).
`co(11,1);    int csr_att`co();
        The attribute to use when displaying the cursor position.
`co(11,1);    int first_att`co();
        The attribute to use for the menu entry selection character.
        Typically you would use the same background color as back_att,
        but a different foreground color.
`co(11,1);    int bdr`co();
        The border style, can be either NO_BDR, SGL_BDR, DBL_BDR,
        SLD_BDR or DUAL_BDR (defined in uw.h).
`co(11,1);    int type`co();
        The menu type, can be either WN_POPUP or WN_NORMAL.  Use the
        former when not using the window manager.
`co(11,1);    MENU *mnp;`co();
        A pointer to the menu to create.

Usage:
    MENU mn;
    int back_att, bdr_att, csr_att, first_att;
    ...
    menu_create(0, 0, 20, 10, M_VERTICAL, back_att, bdr_att,
                            csr_att, first_att, SGL_BDR, WN_NORMAL, *mn);

`co(10,1);/// menu_destroy`co();   `keyword(source,[UW_MENU.C]~menu_destroy);
    This function destroys the menu created with menu_create.  The
    window allocated for the menu is freed.

Prototype:
    void menu_destroy( MENU *mnp );

Parameters:
`co(11,1);    MENU *mnp;`co();
        A pointer to the menu to destroy.

Usage:
    MENU *mnp;
    ...
    menu_destroy(mnp);

`co(10,1);/// menu_set`co();   `keyword(source,[UW_MENU.C]~menu_set);
    This function takes a menu created with menu_create, and places
    it on the screen.  If the menu was defined with type WN_POPUP, the
    area below the window will be saved for later restoration.

Prototype:
    void menu_set( MENU *mnp );

Parameters:
`co(11,1);    MENU *mnp;`co();
        A pointer to the menu to place on the screen.

Usage:
    MENU *mnp;
    ...
    menu_set(mnp);

`co(10,1);/// menu_restore`co();   `keyword(source,[UW_MENU.C]~menu_restore);
    This function takes a menu created with menu_create, placed on
    the screen with menu_set, and removes it from the screen.  If the
    menu was defined with type WN_POPUP, the area below the window is
    restored.  If the menu was defined with type WN_NORMAL and the
    window manager is in use, then the area under the menu will be
    redrawn.

Prototype:
    void menu_restore( MENU *mnp );

Parameters:
`co(11,1);    MENU *mnp;`co();
        A pointer to the menu to restore.

Usage:
    MENU *mnp;
    ...
    menu_restore(mnp);

`co(10,1);/// item_add`co();   `keyword(source,[UW_MENU.C]~item_add);
    This function is used to add an entry into a menu.    An integer
    handle (or id) that you define is passed to identify the entry.
    The menu_do function returns this id when the entry is selected.
    In addition, the index into the string for the "active" character
    is passed.    This is the character in the string that is displayed
    in the first_att color upon display, and is used when a key on
    the keyboard is pressed that matches.

Prototype:
    void item_add( char *entry, int id, int first_pos, MENU *mnp );

Parameters:
`co(11,1);    char *entry;`co();
        The string to add to the menu.    This string does not have to
        be the same length as the width of the menu, as the display
        routines of menu_set and menu_do justify the entry for you.
`co(11,1);    int id`co();
        This is an id you define which will be returned to you when
        the menu item is selected in menu_do.
`co(11,1);    int first_pos`co();
        This is an index into the string for the "active" letter.  This
        letter will be used to check against keyboard letters pressed,
        and will be displayed in the first_att color specified in the
        menu_create function.  For example, for the entry "Dos Shell"
        to make the menu_do function return the id with one keypress,
        use a first_pos of 4, which corresponds to the "S" in "Shell".
`co(11,1);    MENU *mnp;`co();
        A pointer to the menu the item is to be added.

Usage:
    #define DOS_SHELL 37
    MENU *mnp;
    ...
    item_add("Dos Shell", DOS_SHELL, 4, mnp);

`co(10,1);/// do_menu`co();   `keyword(source,[UW_MENU.C]~do_menu);
    Call this function after you have called menu_set, and the menu
    will be activated for input from the user.    To retain flexibility,
    you may specify whether the do_menu function should interact
    with the user through the wait_event function, or immediately
    process the global Event variable and return to you.    This gives
    you the ability to use your own event logic if you wish, and
    is useful for menus which are static on the screen, as opposed to
    menus that pop up and restore when finished.    If interaction
    through wait_event is specified, then this function returns
    either the id of the item selected, or 0 if no item is selected.
    If you have do_menu only process the information in the global
    variable Event, then a 0 is returned for each call to do_menu
    that does not have an <Enter> keypress in Event.

Prototype:
    int do_menu( MENU *mnp, int proc_mode );

Parameters:
`co(11,1);    MENU *mnp;`co();
        A pointer to the menu for interaction.
`co(11,1);    int proc_mode`co();
        The processing mode, which can be one of the defines M_GET_EVENT
        or M_PROC_EVENT.    If M_GET_EVENT is used, then the menu will
        get input via the keyboard (or mouse if it exists) until the
        user has either selected one of the items, or pressed the Esc
        key.

Usage:
    MENU *mnp;
    ...
    do_menu( mnp, M_GET_EVENT );

`co(10,1);/// menu_system`co();   `keyword(source,[UW_MENU.C]~menu_system);
    This function was written specifically for the standard top menu
    bar with corresponding drop down menus.  This function gives you
    the option of displaying the top menu upon entry and removing the
    top menu upon exit (a popup menuing system), or simply use the top
    menu previously placed on the screen with menu_set.  When called,
    the function will interact with the user through the keyboard and
    mouse, and return the menu id of the entry selected.  If the Esc
    key was pressed or the mouse clicked off the menu, then a 0 is
    returned.  Upon completion, the global Event variable will contain
    information about the last key or mouse press.

    NOTE: To utilize this function, you must first define your menus
    with menu_create, then add each entry with item_add, being sure
    to define a unique id for each entry.

Prototype:
    int menu_system( MENU *top_mnp, MENU *dropmenu[], int draw_top );

Parameters:
`co(11,1);    MENU *top_mnp;`co();
        A pointer to the vertical main menu.
`co(11,1);    MENU *dropmenu[];`co();
        An array of pointers to a series of drop down menus.
`co(11,1);    int draw_top`co();
        This parameter can be either 1 or 0, and specifies whether the
        menu_system function should handle the initial display of the
        top menu or assume that the top menu is already displayed.
        Using a value of 1 is useful if you wish your menu system to be
        hidden during your program, and only called up with a key.    Use
        a 0 for when your program keeps the top menu on the screen.

Usage:
    MENU *top_mnp;
    MENU *drop_mnp[8];
    ...
    menu_system( top_mnp, drop_mnp, 1);

`co(4,7);─ End ──────────────────────────────────────────────────────────────────────`co();`sound(1024,10);